Release 10.1A: OpenEdge Development:
Progress 4GL Reference

CALL object handle

A handle to a CALL object, which lets you do the following dynamically:

Invoke an external procedure, internal procedure, or user-defined function.
Get or set an attribute.
Run a method.

Syntax

call-object-handle [ :attribute | :method ]

call-object-handle

A handle to a CALL object.

attribute

An attribute of the CALL object.

method

A method of the CALL object. The methods let you set parameters, reset attributes to their default values, and invoke the CALL object.

Attributes

ASYNCHRONOUS attribute	ASYNC-REQUEST-HANDLE attribute	CALL-NAME attribute
CALL-TYPE attribute	EVENT-PROCEDURE attribute	EVENT-PROCEDURE-CONTEXT attribute
IN-HANDLE attribute	IS-PARAMETER-SET attribute	NUM-PARAMETERS attribute
PERSISTENT attribute	RETURN-VALUE attribute	RETURN-VALUE-DATA-TYPE attribute
SERVER attribute

Methods

CLEAR( ) method	INVOKE( ) method
SET-PARAMETER( ) method

Examples

The following fragment dynamically invokes an external procedure nonpersistently:

DEFINE VARIABLE hCall AS HANDLE. CREATE CALL hCall. /*invoke hello.p nonpersistently */ hCall:CALL-NAME = "hello.p". hCall:NUM-PARAMETERS = 1. hCall:SET-PARAMETER( 1, "CHARACTER", "INPUT", "HELLO WORLD"). hCall:INVOKE. /* clean up */ DELETE OBJECT hCall.

The following fragment dynamically invokes an external procedure persistently, then dynamically invokes one of its internal procedures:

DEFINE VARIABLE hCall AS HANDLE. CREATE CALL hCall. /*invoke persis.p persistently */ hCall:CALL-NAME = "persis.p". hCall:PERSISTENT = true. HCall:INVOKE. /* IN-HANDLE is automatically set to the handle of the persistent procedure */ /* invoke internal-persis-proc in persis.p */ HCall:CALL-NAME = "internal-persis-proc". hCall:NUM-PARAMETERS = 1. hCall:SET-PARAMETER( 1, "INTEGER", "INPUT", 333). hCall:INVOKE. /* clean up */ DELETE PROCEDURE hCall:IN-HANDLE. DELETE OBJECT hCall.

The following fragment uses a single CALL object handle multiple times:

DEFINE VARIABLE hCall AS HANDLE. CREATE CALL hCall. /*invoke hello.p nonpersistently */ hCall:CALL-NAME = "hello.p". hCall:NUM-PARAMETERS = 1. hCall:SET-PARAMETER( 1, "CHARACTER", "INPUT", "HELLO WORLD"). hCall:INVOKE. /* reset the CALL object handle */ hCall:CLEAR. /*invoke persis.p persistently */ hCall:CALL-NAME = "persis.p". hCall:PERSISTENT = true. HCall:INVOKE. /* IN-HANDLE is automatically set to the handle of the persistent procedure */ /* invoke internal-persis-proc in persis.p HCall:CALL-NAME = "internal-persis-proc". hCall:NUM-PARAMETERS = 1. hCall:SET-PARAMETER( 1, "INTEGER", "INPUT", 333). hCall:INVOKE. /* clean up */ DELETE PROCEDURE hCall:IN-HANDLE. DELETE OBJECT hCall.

The following fragment gets an attribute:

/* get title of frame */ hCall:IN-HANDLE = myframe_handle. HCALL:CALL-TYPE = GET-ATTR-CALL-TYPE. hCall:CALL-NAME = "TITLE". hCall:INVOKE. Mytitle = hCall:RETURN-VALUE.

The following fragment sets an attribute:

/* set SESSION:NUMERIC-FORMAT to "european" */ hCall:IN-HANDLE = "session". HCALL:CALL-TYPE = SET-ATTR-CALL-TYPE. hCall:CALL-NAME = "numeric-format". hCall:NUM-PARAMETERS = 1. hCall:SET-PARAMETER( 1, "CHAR", "INPUT", "european"). hCall:INVOKE.

The following fragment drives the INVOKE() from a TEMP-TABLE:

/*suppose hRuntt is a temp-table that has one record with the following fields: parm_1 parm_2 ... parm_n run-name nparms datatypes, extent nparms iomodes, extent nparms */ DEFINE INPUT PARAMETER TABLE-HANDLE hRuntt. DEFINE VARIABLE hDtypes AS HANDLE. DEFINE VARIABLE hIOmodes AS HANDLE. DEFINE VARIABLE hCall AS HANDLE. DEFINE VARIABLE i AS INTEGER. hDtypes = hRuntt:BUFFER-FIELD("datatypes"). hIOmodes = hRuntt:BUFFER-FIELD("iOmodes"). hRuntt:FIND-FIRST. CREATE CALL hCall. hCall:CALL-NAME = hRuntt:BUFFER-FIELD("run-name"):BUFFER-VALUE. hCall:NUM-PARAMETERS = hRuntt:BUFFER-FIELD("nparms"):BUFFER-VALUE. FOR i = 1 to hCall:NUM-PARAMETERS. hCall:SET-PARAMETER( i, hDtypes:BUFFER-VALUE(i), hIOmodes:BUFFER-VALUE(i), hRuntt:BUFFER-FIELD(i):BUFFER-VALUE). END. hCall:INVOKE. DELETE OBJECT hCall. /* if there are output parms, get the values from hRuntt:BUFFER-FIELD(i) */

Notes

Invoking logic dynamically requires many more lines of code than does invoking it statically, which can make your program hard to read. For this reason, Progress Software Corporation recommends that you invoke logic dynamically only when absolutely necessary. Specifically, use the CALL object only when you cannot use the RUN statement, the DYNAMIC-FUNCTION() function, or widget:attribute or widget:method syntax, as in the following situations:
To invoke an internal or external procedure whose calling sequence (number of parameters and the data type of each) is unknown at compile time.
Note: But if only the name of the procedure is unknown at compile time, use the RUN statement with the VALUE option—and avoid the CALL object altoghether.
To invoke a function whose calling sequence is unknown at compile time.
Note: But if only the name of the function is unknown at compile time, use the DYNAMIC-FUNCTION() function—and avoid the CALL object altogether.
To reference a widget attribute or method whose name is unknown at compile time.

If you already know the name of the attribute or procedure, you know its syntax, since the name implies certain syntax. And if you know the syntax, you know the calling sequence, since the syntax defines the calling sequence. And if you know the calling sequence, you can use widget:attribute or widget:method syntax—and avoid the CALL object altogether.

To create a CALL object, use the following syntax:

CREATE object handle [ IN widget-pool ]

For example:

CREATE CALL hCall.

Note: Unlike most 4GL objects, the CALL object, by default, goes into the SESSION widget pool, not into the closest unnamed widget pool.
To delete a CALL object, use the following syntax:

DELETE OBJECT handle

For example:

DELETE OBJECT CALL hCall.

Since the CALL object, by default, goes into the SESSION widget pool, not into the closest unnamed widget pool, to delete a CALL object created when the IN widget-pool option is not used, use the DELETE object handle syntax explicitly.

See also

RUN statement